
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
  <title>CMP0003 &mdash; CMake 3.16.5 Documentation</title>

    <link rel="stylesheet" href="../_static/cmake.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    
    <link rel="shortcut icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMP0002" href="CMP0002.html" />
    <link rel="prev" title="CMP0004" href="CMP0004.html" />
  
 

  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="CMP0002.html" title="CMP0002"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="CMP0004.html" title="CMP0004"
             accesskey="P">previous</a> |</li>
  <li>
    <img src="../_static/cmake-logo-16.png" alt=""
         style="vertical-align: middle; margin-top: -2px" />
  </li>
  <li>
    <a href="https://cmake.org/">CMake</a> &#187;
  </li>
  <li>
    <a href="../index.html">3.16.5 Documentation</a> &#187;
  </li>

          <li class="nav-item nav-item-1"><a href="../manual/cmake-policies.7.html" accesskey="U">cmake-policies(7)</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="cmp0003">
<span id="policy:CMP0003"></span><h1>CMP0003<a class="headerlink" href="#cmp0003" title="Permalink to this headline">¶</a></h1>
<p>Libraries linked via full path no longer produce linker search paths.</p>
<p>This policy affects how libraries whose full paths are NOT known are
found at link time, but was created due to a change in how CMake deals
with libraries whose full paths are known.  Consider the code</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>target_link_libraries(myexe /path/to/libA.so)
</pre></div>
</div>
<p>CMake 2.4 and below implemented linking to libraries whose full paths
are known by splitting them on the link line into separate components
consisting of the linker search path and the library name.  The
example code might have produced something like</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>... -L/path/to -lA ...
</pre></div>
</div>
<p>in order to link to library A.  An analysis was performed to order
multiple link directories such that the linker would find library A in
the desired location, but there are cases in which this does not work.
CMake versions 2.6 and above use the more reliable approach of passing
the full path to libraries directly to the linker in most cases.  The
example code now produces something like</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>... /path/to/libA.so ....
</pre></div>
</div>
<p>Unfortunately this change can break code like</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>target_link_libraries(myexe /path/to/libA.so B)
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">B</span></code> is meant to find <code class="docutils literal notranslate"><span class="pre">/path/to/libB.so</span></code>.  This code is wrong
because the user is asking the linker to find library B but has not
provided a linker search path (which may be added with the
link_directories command).  However, with the old linking
implementation the code would work accidentally because the linker
search path added for library A allowed library B to be found.</p>
<p>In order to support projects depending on linker search paths added by
linking to libraries with known full paths, the <code class="docutils literal notranslate"><span class="pre">OLD</span></code> behavior for this
policy will add the linker search paths even though they are not
needed for their own libraries.  When this policy is set to <code class="docutils literal notranslate"><span class="pre">OLD</span></code>, CMake
will produce a link line such as</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>... -L/path/to /path/to/libA.so -lB ...
</pre></div>
</div>
<p>which will allow library B to be found as it was previously.  When
this policy is set to NEW, CMake will produce a link line such as</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>... /path/to/libA.so -lB ...
</pre></div>
</div>
<p>which more accurately matches what the project specified.</p>
<p>The setting for this policy used when generating the link line is that
in effect when the target is created by an add_executable or
add_library command.  For the example described above, the code</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
add_executable(myexe myexe.c)
target_link_libraries(myexe /path/to/libA.so B)
</pre></div>
</div>
<p>will work and suppress the warning for this policy.  It may also be
updated to work with the corrected linking approach:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
link_directories(/path/to) # needed to find library B
add_executable(myexe myexe.c)
target_link_libraries(myexe /path/to/libA.so B)
</pre></div>
</div>
<p>Even better, library B may be specified with a full path:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>add_executable(myexe myexe.c)
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
</pre></div>
</div>
<p>When all items on the link line have known paths CMake does not check
this policy so it has no effect.</p>
<p>Note that the warning for this policy will be issued for at most one
target.  This avoids flooding users with messages for every target
when setting the policy once will probably fix all targets.</p>
<p>This policy was introduced in CMake version 2.6.0.  CMake version
3.16.5 warns when the policy is not set and uses <code class="docutils literal notranslate"><span class="pre">OLD</span></code> behavior.  Use
the <span class="target" id="index-0-command:cmake_policy"></span><a class="reference internal" href="../command/cmake_policy.html#command:cmake_policy" title="cmake_policy"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">cmake_policy()</span></code></a> command to set it to <code class="docutils literal notranslate"><span class="pre">OLD</span></code> or <code class="docutils literal notranslate"><span class="pre">NEW</span></code> explicitly.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <code class="docutils literal notranslate"><span class="pre">OLD</span></code> behavior of a policy is
<span class="target" id="index-0-manual:cmake-policies(7)"></span><a class="reference internal" href="../manual/cmake-policies.7.html#manual:cmake-policies(7)" title="cmake-policies(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">deprecated</span> <span class="pre">by</span> <span class="pre">definition</span></code></a>
and may be removed in a future version of CMake.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="CMP0004.html"
                        title="previous chapter">CMP0004</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="CMP0002.html"
                        title="next chapter">CMP0002</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/policy/CMP0003.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="CMP0002.html" title="CMP0002"
             >next</a> |</li>
        <li class="right" >
          <a href="CMP0004.html" title="CMP0004"
             >previous</a> |</li>
  <li>
    <img src="../_static/cmake-logo-16.png" alt=""
         style="vertical-align: middle; margin-top: -2px" />
  </li>
  <li>
    <a href="https://cmake.org/">CMake</a> &#187;
  </li>
  <li>
    <a href="../index.html">3.16.5 Documentation</a> &#187;
  </li>

          <li class="nav-item nav-item-1"><a href="../manual/cmake-policies.7.html" >cmake-policies(7)</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2000-2019 Kitware, Inc. and Contributors.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.3.1.
    </div>
  </body>
</html>